孪大师 CIMPro 虚拟仿真数字样机编辑器 · Web3D 版技术方案
| 项目 | 内容 |
|---|
| 版本 | V2.0（纯 Web3D / Three.js 路线） |
| 日期 | 2026-08-08 |
| 配套交付 | ① CIMPro_Web3D数字样机编辑器.html（编辑器，可直接使用）② CIMPro_课件播放器.html（学员端播放器）③ 公网演示链接（见第 6 章） |
| 与 V1.1 的关系 | V1.1 为 UE5 路线方案；本文档为完全基于 Web3D 的并行路线，不使用任何桌面引擎 |
1. 路线定位与选择理由
客户诉求变化：模型由客户 3ds Max 团队按规范预处理（轻量化、轴心、层级、删减冗余构件），编辑器不再承担 CAD 转换；发布形态要"直接分享链接"，不需要 exe / 云渲染。
因此本路线：编辑器本身即 Web 应用（Three.js），编辑、预览、发布全在浏览器完成，课件 = glTF + JSON，学员点开链接即学。
| 维度 | UE5 路线（V1.1） | Web3D 路线（V2.0，本文档） |
|---|
| 保真度 | 高（Nanite/光照/材质） | 中高（PBR 足够培训场景） |
| 分发 | exe / 串流 / Web 包 | 纯链接，零安装 |
| 开发成本 | 高（引擎团队） | 低（前端团队即可） |
| 模型管线 | FBX/glTF → UE 资产 | glTF 原生，编辑器与播放器同一格式 |
| 大模型承载 | 千万级三角面 | 建议 ≤ 100 万三角面（需轻量化） |
| 适用 | 重保真、涉密内网、VR | 快速铺量、远程培训、客户演示 |
两条路线共用同一套课件 JSON 契约（flows.disassembly / flows.assembly），未来可双端发行。
2. 模型交付规范（给客户 3ds Max 团队）
编辑器不做 CAD 转换，模型质量依赖预处理规范（这是项目成功的关键约束）：
- 拆分粒度：按"可拆装构件"拆分独立对象，一个构件一个对象；
- 命名：对象名 = 工艺文件中的构件名（课件内显示名、JSON partName 全链路同源）；
- 轴心点（最常见问题）：每个构件的轴心必须在其几何中心或装配基准点——错误轴心会导致旋转/拆装动画"绕远处飞"。编辑器内置「📍 轴心」修正工具兜底（包围盒中心 / 底面中心 / 世界原点三件套，对标 Blender Set Origin）；
- 层级：按总成建立空节点分组（编辑器大纲视图原样呈现，并可在编辑器内二次打组）；
- 删减：删除内部不可见构件、装饰件；单课件建议 ≤ 100 万三角面；
- 格式：glTF/GLB（首选）或 FBX；Y-up、米制单位、PBR 材质贴图打包。
3. 编辑器功能清单（已全部在原型中实现）
3.1 Web 3D 编辑器通用能力（对标 three.js Editor / Blender / Figma 范式调研结论）
| 功能 | 实现 |
|---|
| 大纲视图 | 树状层级、复选多选、按组全选、双击重命名、显隐、删除、搜索过滤（Ctrl+F）、打组/解组（Ctrl+G） |
| 变换 | 三轴 Gizmo 移动/旋转/缩放（W/E/R），世界/局部坐标系切换（Q），吸附步进（0.25m/15°），编辑态拖动即改初始位 |
| 自由拖拽模式 | 🖐 开关，开启后鼠标直接拖动构件（相机平面拖拽） |
| 相机导航 | OrbitControls 环绕/平移/缩放，F 聚焦选中，🎥 复位 |
| 轴向指示 Gizmo | 视口右下角 ViewHelper，点击轴头直接切换视角 |
| 轴心修正 | 包围盒中心 / 底面中心 / 世界原点 |
| 撤销/重做 | Ctrl+Z / Ctrl+Y（步骤快照栈） |
| 自动保存 | 30 秒间隔写入 localStorage + 手动导出 .vtproj 工程文件 |
3.2 课件业务能力（V2.2 增强）
- 框选与多选（V2.2 新增）：三维视图「🔲 框选」模式左键拖框多选构件（结果进入批量勾选）；大纲视图复选框 + Ctrl/Shift 点击多选；与自由拖拽/变换手柄互斥防冲突。
- 新建项目清空场景（V2.2 新增）：一键完整复位——清空步骤/分组/材质/灯光/导入模型/动画/撤销栈，恢复默认样机与默认双灯。
- 动画模型导入（V2.2 新增）：支持含动画的 glTF/GLB/FBX，含骨骼动画（SkinnedMesh）与变形目标（Morph）；导入后左侧「模型动画」面板逐段播放/暂停/全部停止。
- 并行组步骤（V2.1 新增）：步骤带"并行组号"，同组号构件不分先后（典型场景：一组 8 颗螺栓先拧哪颗都正确）。步骤卡片显示组号与「⧉ 并行×N」徽标；培训模式同组目标同时高亮、考核模式同组任意顺序均判定正确；遮挡检测按组号判断（同组互不阻挡）；批量面板可一键"同一并行组号"。
- PBR 材质系统（V2.1 新增）：内置 11 种工业常用材质预设（抛光钢/拉丝钢/铸铁/铝合金/紫铜/黄铜/镀铬/防锈漆红蓝/工程塑料/橡胶），点击即赋予选中构件；基础色/金属度/粗糙度/环境反射四维参数实时微调；支持批量赋予勾选构件、一键恢复原始材质。
- 物理灯光系统（V2.1 新增）：可创建/调整/删除平行光、点光源、聚光灯（颜色/强度/位置，支持三轴手柄拖动灯位）；实时阴影（PCFSoft，质量 512~4096、偏移可调、总开关）；全局环境反射（IBL 环境贴图）强度可调；ACES 电影级色调映射 + 曝光调节。
- 撤销/重做升级（V2.1）：全局快照覆盖步骤、构件初始位、材质、灯光、工具库；Ctrl+Z / Ctrl+Y；变换拖动开始前自动快照；滑条参数"按下拍快照、松开入栈"。（注：删除构件为破坏性操作，不可撤销，操作前有确认提示。）
- 步骤配置：点选构件添加拆卸步骤；每步可配动作类型/移除方向（六向轴+径向）/距离/时长；安装序列自动按拆卸逆序生成，拆卸/安装双流程一键切换；
- 遮挡检测：沿移除方向射线扫掠，自动识别"被谁挡住"，步骤卡片 ⚠ 提示；「自动排序」按拓扑依赖重排（被挡构件排在其阻挡件之后）；
- 批量设置：大纲勾选（可按组）→ 统一方向/距离/时长/工具/提示模板（{名称} 占位符）→ 一键批量生成或更新步骤，应对几十~几百构件的设备；
- 引导提示：提示文本、高亮颜色/方式（描边/脉冲/半透明）、引导箭头、3D 标签、TTS 语音播报、出现延迟——均可预览；
- 相机：每步"记录当前视角"/"自动取景（包围盒聚焦）"，飞行时长与缓动可配（平滑/匀速/瞬间）；
- 界面：步骤面板/工具栏/构件信息卡/计时器四个开关实时决定学员端 UI；主题色与课件名可配；
- 工具：内置 9 种常用工具，支持自定义增删（图标+名称）；培训/考核强制"先选对工具再操作构件"，选错判错；
- 考核：时长、顺序/工具/求助扣分、合格线全可配；红闪反馈、超时交卷、操作日志；成绩报告 + CSV 导出；
- 认知模式：全构件爆炸图 + 每个构件名称标签实时跟随；
- 悬停：hover 高亮 + 构件名/总成/步骤号浮动标签。
3.3 播放器（学员端）
独立 player.html：欢迎页（课件名+学习目标）→ 演示/培训/考核三模式 × 拆装双流程 → 工具栏 → 提示气泡/语音 → 考核 HUD → 成绩报告。可「打开课件包」加载编辑器导出的 course.json + model.glb（也支持仅加载 JSON 配内置模型演示）。
4. 数据契约（cimpro-webcourse v2.0）
{ "format": "cimpro-webcourse", "version": "2.0", "name": "...", "model": "xxx.glb",
"flows": { "disassembly": [{ "seq":1, "partName":"顶盖", "action":"disassemble",
"axis":"y+", "dist":2.8, "dur":1.6, "tool":"行车吊具 + 吊带",
"hint":"...", "hintColor":"#f5a524", "camera":{"pos":[...],"tgt":[...]} }],
"assembly": [ /* 拆卸逆序，action=assemble */ ] },
"modes": { "demo": {...}, "train": {...}, "exam": { "durationMin":10, "orderErr":5, "toolErr":3, "hintCost":2, "pass":80 } },
"ui": { "stepPanel":true, "toolBar":true, "partInfo":true, "timer":false, "theme":"#3d9dff" } }- 构件匹配键 =
partName（即模型对象名），所以模型命名规范是硬约束；
- Babylon.js 播放器可按同一 JSON 契约实现（glTF 为其原生格式），无需改编辑器。
5. 已知限制与后续迭代
| 限制 | 说明 | 迭代方向 |
|---|
| 超大模型 | Web 端建议 ≤100 万三角面 | DRACO/ meshopt 压缩、LOD、分块加载 |
| 撤销粒度 | 当前覆盖步骤操作 | Command 模式全操作回退 |
| 节点流程图 | 线性只读 | 分支/条件节点 |
| 多人协同 | 无 | 课程云端工程 + 权限 |
| 考核日志回传 | 本地 CSV | 对接 LMS（xAPI/SCORM） |
| 移动端 | 桌面优先 | 触控手势（双指平移/捏合缩放） |
6. 演示入口
- 编辑器（公网）：见部署链接（index.html）
- 本地：双击两个 HTML 文件即可运行（需联网加载 Three.js CDN）
附录：V3.0 架构升级记录（2026-08-09）
- 层级完整导入：glTF/FBX 整树挂载，大纲递归渲染全部节点与层级（📂分支/🧩叶子/缩进），跳过骨骼节点；删除构件级联子构件。
- 专业化 UI 分区：左侧=大纲/材质/灯光/历史（美术与结构），右侧=步骤/引导/相机/界面/工具/考核（逻辑），底部=逻辑流程图/动画时间轴。
- PBR 材质工作站：MeshPhysicalMaterial 全通道（基础色/金属度/粗糙度/法线/AO/发光）+ 每通道贴图插槽（外部贴图导入替换，aoMap 自动补 uv1）+ 材质吸管（继承导入模型全部通道与贴图）+ 31 种分类预设（金属10/玻璃5/塑料5/混凝土5/发光5/标准1）。
- 另存为：File System Access API（showSaveFilePicker）真选存储位置，降级为下载导出。
- 历史记录：带标签与时刻的操作快照栈，点击任意记录回溯，可清空；与撤销/重做共享快照机制。
- 真实感渲染：EffectComposer + SSAOPass（环境光遮蔽）+ IBL 环境反射 + ACES 色调映射 + PCFSoft 阴影。
- 框选/全选：三维框选 + 大纲 Ctrl/Shift/Ctrl+A。
- 动画时间轴：剪辑单击/拖入轨道、关键帧菱形显示、拖动关键帧改时机（就地改 track.times，interpolant 引用生效）、播放/暂停/停止/scrub、工程保存 animEdits、glb 导出携带 animations。
- 测试基建：puppeteer-core + swiftshader 无头浏览器冒烟测试 22 项（真实模型：码垛机器人骨骼动画、配电箱 Sketchfab 层级）。
附录：V3.2 功能迭代记录（2026-08-09）
- 选择体系修复与清空：全选/框选后可一键删除所选（Delete 键批量优先）；顶栏「🧹 清空」重置全部内容。
- 动画目录树：时间轴左侧按模型分组的动画库，剪辑单击/拖拽入轨，模型级播放/停止。
- 剖切系统：平面剖切（轴/位置/反向）+ 体剖切（中心/尺寸），范围限定（全部/仅勾选/排除勾选），基于 three.js clippingPlanes（对标 xeokit SectionPlane / BIMFACE 剖切盒调研结论）。
- 测量工具：距离/高度/角度/面积，吸附顶点/边中点/面中心（20px 屏幕阈值），面积双击结束（Newell 算法）。
- 内置模型库：默认 5 分类（建筑/机械/武器/植物/载具），分类可增删改名，模型上传/载入/删除，IndexedDB 持久化。
- 3D 高斯泼溅 PLY 导入：@mkkellogg/gaussian-splats-3d（DropInViewer + SceneFormat.Ply + sharedMemoryForWorkers:false 规避跨域隔离要求），失败自动降级 PLYLoader 点云；犰狳 7.9MB 真实 splat 模型实测通过。
- 时间轴增强：播放头/标尺自由拖拽寻址；倒放（负 timeScale）、循环开关、0.5×-4× 倍速。
- 竞品调研结论（xeokit/BIMFACE/ThingJS/Spline/PlayCanvas）：剖切盒六面拖拽与单面 gizmo 两派、测量吸附 GPU picking、资产面板文件夹树+拖拽入场景——已纳入后续路线。
附录：V4.0 重大迭代记录（2026-08-09）
- 导入材质修正：自动修复导出器误标 BLEND 导致的整体透明（dabai 类 Mixamo 模型）、缺法线自动重建；资源注册表流程（导入→资源库→置入场景，对标 Babylon Assets Browser）。
- 物理相机：场景可创建多个相机对象（大纲管理），FOV/焦距（联动换算）/对焦距离/光圈/曝光补偿/DOF 景深（BokehPass 预览）。
- 实例复制：Ctrl+C/V、Shift+拖动手柄复制、批量线性/环形阵列复制；clone 共享几何体与材质（实例级内存共享）。
- 漫游模式：轨道/鸟瞰/第一人称（PointerLockControls+WASD/QE，Shift 加速）。
- OBJ/STL 导入：层级（OBJ 按 o/g 分组）保留；STL 单网格注册。
- 属性面板：构件（TRS 九项+材质入口）、灯光（含色温 K→RGB）、相机（全物理参数）统一 Inspector。
- 天空组件：物理大气（Sky addon）+ 太阳时刻/方位 + 天气系统（晴/多云/阴/雨/雪联动粒子与雾）+ GI 由天空实时重烘焙（PMREM）。
- 粒子系统：火焰/烟雾/爆炸/水流/雨/雪/落叶 7 预设，发射器全参数面板，单帧重生上限防卡顿，工程保存/快照撤销全支持。
- GIS 模块：真实经纬度（Web 墨卡托）+ Esri 全球影像 + AWS Terrarium 全球 DEM 高程，一键生成地形块；3D Tiles（tileset.json，b3dm 自解析）在线加载；OSGB 给出转换指引；LCC/LCC2 预留 LoaderRegistry 注册接口（可挂其域官方 SDK）。
- 时间轴缩放：➕/➖ 调节像素/秒刻度（30~600px/s）。
- 内置模型库：Khronos 官方 PBR 样例 5 款（受损头盔/复古音箱/水壶/灯笼/玩具车，全贴图 3.6-10MB），首启自动灌入 IndexedDB。
- 有声教程：TTS 解说 + 真实模型实操录屏合成，嵌入手册。
附录：V4.1 交付版迭代记录（2026-08-10）
组可选中整体移动/删除 · 发射器进大纲 · 粒子发射形状(点/盒/球/面)+方向+PNG贴图 · GIS默认接通全球影像+DEM · 资源库文件夹CRUD · 时间轴循环/倒放修复+关键帧动画制作(模型/灯光/相机/发射器的位置旋转缩放材质发光强度打帧) · 第一/三人称漫游修复 · 工具栏六组重排 · 清空彻底(含相机发射器) · 大纲拖拽改父子 · FBX(7500)/OBJ+MTL+贴图多文件导入实测 · 手册新窗口 · 版本号/官网链接 · 集成导出(iframe+URL参数) · 属性面板XYZ拖动调值 · 体积云+指数雾天气 · 全量真实模型回归17/17通过0报错。